home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / ABox 1.9.5 / Header Files / ABoxDefs.h < prev    next >
Encoding:
Text File  |  1995-10-26  |  16.0 KB  |  405 lines  |  [TEXT/MMCC]
  1. /*    
  2.     Copyright © 1991-1995 by TopSoft Inc.  All rights reserved.
  3.  
  4.     You may distribute this file under the terms of the TopSoft
  5.     Artistic License, accompanying this package.
  6.     
  7.     This file was developed by George (ty) Tempel in connection with TopSoft, Inc..
  8.     See the Modification History for more details.
  9.  
  10. Product
  11.     About Box
  12.  
  13. FILE
  14.     ABoxDefs.h
  15.  
  16. NAME
  17.     ABoxDefs.h, part of the ABox project source code,
  18.     responsible for handling the AboutBox stuff.
  19.  
  20. DESCRIPTION
  21.     This file contains defines for the about box modules.
  22.     
  23. DEVELOPED BY
  24.     George (ty) Tempel                ttempel@monmouth.com
  25.     All code in this file, and its associated header file was
  26.     Created by George (ty) Tempel in connection with the TopSoft, Inc.
  27.     "FilterTop" application development, except where noted.
  28.  
  29. CARETAKER - George (ty) Tempel <ttempel@monmouth.com>
  30.      Please consult this person for any changes or suggestions to this file.
  31.  
  32. MODIFICATION HISTORY
  33.  
  34.     dd mmm yy    -    xxx    -    patchxx: description of patch
  35.     ?? Oct 92    -    ty    -    Initial Version Created
  36.     ?? Jul 93    -    ty    -    d18, d19 fixes
  37.     05-oct-93    -    ty    -    d25/26 changes for apple recommended
  38.                             greys for the 3d effects (see develop #15)
  39.     19-nov-93    -    ty    -    d26 changes for improved update handling
  40.     26-jan-94    -    ty    -    1.0a3 changed "int" to "short int"
  41.     26-jan-94    -    ty    -    1.0a3 conversions for PowerPC/Universal-Headers conversion
  42.     01-feb-94    -    ty    -    1.0a3 changes to remove "register" keyword, remove use of "nrequire"
  43.                             and "require" error checking as sometimes they are confusing,
  44.                             fixed possible bug when dismissing the dialog while a movie
  45.                             is playing, and other small things. Mostly tried to edit
  46.                             the code to comply with the bulk of the Coding Standards document
  47.                             that Jim Brunner produced (nice work jim!)
  48.     22-feb-94    -    ty    -    1.0a4 patches to work better with universal headers, clear
  49.                             up some minor stuff, add FTQsort for universal header
  50.                             portability. Fixed some logic to better deal with the
  51.                             user having moved or eliminated our access to the FTSlides
  52.                             folder.
  53.     28-feb-94    -    ty    -    1.0a4 work to eliminate FTQsort (found a better
  54.                             way of fixing the header file collision created by the
  55.                             introduction of Apple Universal Headers into the Symantec
  56.                             compiler tree). Fixed up some of the user safety checks,
  57.                             return values, etc. Cleaned up more of the Universal Header
  58.                             support, and provided Universal Headers support in the
  59.                             ModalDialog() use.
  60.     09-mar-94    -    ty    -    1.0a4p2 Created functions:
  61.                             CreateTopicList(), CreateSlideList(), CreateSlideNumbers()
  62.                             to simplify dynamic memory management; GetABoxDialog(), 
  63.                             SetABoxDialog(), GetABoxList(), SetABoxList(), GetABoxText(),
  64.                             SetABoxText(), GetABoxListVScroll(), SetABoxListVScroll(),
  65.                             GetABoxListHScroll(), SetABoxListHScroll() for abox structure
  66.                             management
  67.     17-mar-94    -    ty    -    1.0a5 applied edits to ensure all calls check their
  68.                             parameters for validity and have AssertStr() statements
  69.                             that can be conditionally compiled. Also, applied the
  70.                             multithreaded modal dialog tips from _develop_ #17, p 89-90. Also
  71.                             started to document the daylights out of everything.
  72.     14-apr-94    -    ty    -    metropolis edits: adding kABTopicSlideResource 'TSAb' support
  73.                             for all slide/topic files including the application. Any file
  74.                             that should appear in the topic list _must_ have a TSAb resource
  75.                             within it (and only one!) that is a 1-based list of all
  76.                             resource family ID's to use as slides, in the order of
  77.                             appearance. So a TSAb resource that should display
  78.                             resources of ID's 400, 128, 345 should specify the
  79.                             slide ID's 400, 128, 345 in that order. No sorting is
  80.                             performed by the abox. Furthermore, the application fork
  81.                             should have a TSAb resource within it to designate
  82.                             'primary slides' (which we had called default slides). Those
  83.                             slides are always attached to the "About this application..."
  84.                             topic at the top of the topic list.
  85.     28-apr-94    -    ty    -    1.0a9 edits: cleaned up constants in code, document more
  86.                             functionality and ensure error checking.
  87.     2-may-94    -    ty    -    1.0a9p2 edits: restored the original TS copyright header
  88.     3-may-94    -    ty    -    1.0a9p3 edits: added calling chain information
  89.     5-may-94    -    ty    -    1.0a9p4 edits: added speech manager support for clicking
  90.                             on the slide field area. If there is a kABstringResource
  91.                             and the speech manager is present then the 'title' will
  92.                             be spoken in the system's default voice. Cool! As such,
  93.                             I have added the functions IsSpeechAvailable() and DoSpeaking()
  94.     6-jun-94    -    ty    -    1.0a9p7 edits: changed function return type of CountAndLoadElementResources
  95.                             to OSErr...the ResourceInfoPtr was redundant since it is contained 
  96.                             within the SlideListPtr structure
  97.     8-jun-94    -    ty    -    1.0a9p8 edits: THE BIG ONE!
  98.                             1.    I mostly cleaned up some loop conditionals and some error
  99.                                 checking in order to debug the problem of the Great Crashing
  100.                                 About Box under the PowerPC Mac 68k emulator. Most visibly
  101.                                 I have reorganized the ABox source into many source files
  102.                                 of much smaller and more manageable sizes. A few key loop
  103.                                 conditionals were poorly constructed and _just_might_
  104.                                 cause intermittent problems. I have tested the code on a
  105.                                 PowerMac 6100/60-AV 8/250 with Metrowerks DR/3 release
  106.                                 and it works without problems. In light of the new
  107.                                 source for the ABox, you should remove any FTAboutBox.c
  108.                                 and FTAboutBox.h files that you have in your project and
  109.                                 incorporate the files in this distribution. If you wish to
  110.                                 keep things neater, leave the new ABox code in the subfolders
  111.                                 provided in this distribution.
  112.                                 
  113.                             2.    I have changed the cosmetics of the topic list. I am letting
  114.                                 the List Manager determine the best vertical size for the cells,
  115.                                 but I am adjusting the height of the list to avoid cutting off
  116.                                 any cells part way. I have always used the List Manager option to
  117.                                 auto-scroll to the current cell, but if even a single pixel of
  118.                                 the current cell is showing then the auto-scroll option has
  119.                                 no effect. What I do now is downward-adjust (shorten) the height
  120.                                 of the list to force the "cut-off" topic out of sight and let
  121.                                 the List Manager take over. Long and short of it: it works fine now.
  122.                             
  123.                             3.    Once debugging on the PowerMac (wow is it fast! even when
  124.                                 debugging the 68k abox code!) I noticed that I had a call
  125.                                 duplicated in a body, which caused all slide elements to actually
  126.                                 be processed twice...with sound resources this is most noticeable,
  127.                                 or rather only noticeable, on a PowerMac, since the sound starts
  128.                                 to play, is killed, then played again (all other things are
  129.                                 way to fast to detect). The duplicated call came from an editing
  130.                                 session where code was duplicated instead of moved. I removed the
  131.                                 duplicate and now it all works.
  132.                                 
  133.                             4.    I found a rather severe bug in the code regarding the
  134.                                 usage of the external (to the abox) window updater function.
  135.                                 I forgot to make edits for UPP/PowerPC usage, and as such
  136.                                 the thing just might have crashed and burned on PPC boxes in
  137.                                 native mode. I believe that I have corrected the problem.
  138.                                 
  139.                             5.    The calling code (in our case, the function inside FTMenus.c)
  140.                                 for the ABox _must_ create the external window updater UPP.
  141.                                 Previously I had the calling code pass the function pointer,
  142.                                 but in the spirit PPC-dom, the caller should create the UPP
  143.                                 and hand the UPP over to the abox.
  144.  
  145.     20-july-94    -    ty    -    initial version for ABox Project released
  146.     23-may-95    -    ty    -    changes for compatibility with the CodeWarrior CW6
  147.                             release and the associated Universal Headers from Apple:
  148.                             most methods that returned references now have "Ref" at
  149.                             the end of their methods names to prevent possible collisions
  150.                             with datatypes and classes of the same name (older versions
  151.                             of the compiler didn't have a problem with this).
  152.     25-oct-95    -    ty    -    changes for "const" usage under CW7; simplification of Boolean
  153.                             query methods
  154. */
  155.  
  156. /*===========================================================================*/
  157.  
  158. /*========== Exclusion Macros ============*/
  159.  
  160. #pragma    once
  161.  
  162. #ifndef    _ABoxDefs_
  163. #define    _ABoxDefs_
  164.  
  165.  
  166. /*============ Header Files ==============*/
  167.  
  168.  
  169. /*================ Macros ================*/
  170.  
  171.  
  172.  
  173. /*============== Constants ===============*/
  174.  
  175. //    dialog box & items
  176.  
  177. //    _DialogDispatch is the trap for the new (system 7) dialog manager
  178. //    calls SetDefaultItem, SetCancelItem, SetCursorTracking, which make
  179. //    life a little easier for modal dialog programmers.
  180. #define     _DialogDispatch                     0xAA68    // 1.0a2 SJ moved over from FTAboutBox.c
  181.  
  182. //    Unimplemented Trap number
  183. #define     kABUnimplTrap        0x9f        //    The "unimplmented" trap num
  184.  
  185.  
  186. //    kABownerNameString and kABmachineNameString are what were referred to
  187. //    as the "chooser name" information from pre-system 7 systems. These
  188. //    string resources come from the Sharing Setup control panel and are used
  189. //    by the about box to place the user's name into the topic list
  190. //    to personalize the about box.
  191. #define        kABownerNameString                    -16096
  192. #define        kABmachineNameString                -16413
  193.  
  194. //    dialog and dialog placement defines
  195. //
  196. //    kABreduceFactor is used by ScaleRectToFit() to adjust the
  197. //    geometry of a rectangular area to better (proportionally) fit
  198. //    a given area.
  199. #define        kABreduceFactor                        (0.75)
  200.  
  201. //    kABdialogSpacing is used by ResizeFields() to adjust the
  202. //    positioning of the various slide elements of the about box.
  203. #define        kABdialogSpacing                    (2)
  204.  
  205. //    kABtextFace, kABtextSize, kABtextFont are used to define
  206. //    the quickdraw text characteristics of the about box dialog
  207. //    elements, particularly the topic list and the slide title.
  208. //    If slide-text items have style records, those are used to
  209. //    define the slide-text, otherwise these characteristics play
  210. //    there are well.
  211. #define        kABtextFace                            (0)    // plain
  212. #define        kABtextSize                            (9)    // size
  213. //    1.0a9p8 ty...changed the kABtextFont to the default application font
  214. //#define        kABtextFont                            (geneva)
  215. #define        kABtextFont                            (applFont)
  216.  
  217. //    kABtitleMaxHeight defines the maximum height of a slide
  218. //    title block in the slide area.
  219. //#define        kABtitleMaxHeight                    (short)(2.5 * kABtextSize)        //    d26 ty
  220.  
  221. //    kABscrollBarWidth and kABscrollBarMinLength are used
  222. //    in the about box code to describe, respectively,
  223. //    the width and minimum length of the scroll bar used by the
  224. //    DoText() function to draw/display text records in the slide area.
  225. #define        kABscrollBarWidth                    (16)
  226. #define        kABscrollBarMinLength                (55)
  227.  
  228.  
  229. //    string resources
  230. //
  231. //    kABStrings is a STR# resource containing some general
  232. //    purpose strings for the about box.
  233. #define        kABStrings                            5001
  234. #define        kABunknownUserInfo                    1
  235. #define        kABfolderSlide                        2
  236. #define        kABdefaultTopicName                    3
  237. #define        kABdefaultTopicNotice                4
  238. #define        kAByourNameHereFile                    5
  239.  
  240. //    the kABfolderTextSlide resource is a TEXT/styl
  241. //    combination that explains why nothing interesting
  242. //    has happened when the user selected a folder in the
  243. //    topic list.
  244. #define        kABfolderTextSlide                    5001
  245.  
  246.  
  247. //    kABErrorStrings is a STR# resource containing
  248. //    all of the error strings used in reporting errors to the
  249. //    user or programmer. This list will most likely continuously
  250. //    grow as features are added to the about box.
  251. #define        kABErrorStrings                        5002
  252. #define        kABErrMemoryAllocated                1
  253. #define        kABErrMemoryDeallocated                2
  254. #define        kABErrMemoryAllocationFailed        3
  255. #define        kABErrNoQuickTime                    4
  256. #define        kABErrDialogMgrTrapsMissing            5
  257. #define        kABErrBadArgStr255                    6
  258. #define        kABErrBadArgStringPtr                7
  259. #define        kABErrBadArgTopicDialogPtr            8
  260. #define        kABErrBadArgListHandle                9
  261. #define        kABErrBadArgNumberOutOfRange        10
  262. #define        kABErrBadArgTopicListPtr            11
  263. #define        kABErrBadArgResourceInfoPtr            12
  264. #define        kABErrBadArgSlideListPtr            13
  265. #define        kABErrDialogItemNumberOutOfRange    14
  266. #define        kABErrBadArgDialogPtr                15
  267. #define        kABErrBadArgControlHandle            16
  268. #define        kABErrBadArgRectPtr                    17
  269. #define        kABErrBadArgFileFolderCountPtr        18
  270. #define        kABErrBadArgShortPtr                19
  271. #define        kABErrBadArgTopicPtr                20
  272. #define        kABErrBadArgSlideNumberPtr            21
  273. #define        kABErrBadResourceHandlingTable        22
  274. #define        kABErrBadResourceHandlingTableCount    23
  275. #define        kABErrProblemsLoadingTopicSlideInfo    24
  276. #define        kABErrProblemsCheckingControlStates    25
  277. #define        kABErrBadArgWindowPtr                26
  278. #define        kABErrBadArgTEHandle                27
  279. #define        kABErrBadUpdateWindowUPP            28
  280. #define        kABErrBadArgEventRecordPtr            29
  281. #define        kABErrProblemsLoadingTopics            30
  282. #define        kABErrProblemsCreatingTopicList        31
  283. #define        kABErrBadArgSoundHandle                32
  284. #define        kABErrSndPlaySync                    33
  285. #define        kABErrSndPlayAsync                    34
  286. #define        kABErrBadArgStrHandle                35
  287. #define        kABErrBadArgTextHandle                36
  288. #define        kABErrQuickTimeErrorCatch            37
  289. #define        kABErrBadArgFSSpecPtr                38
  290. #define        kABErrQuickTimeOpenMovieFile        39
  291. #define        kABErrQuickTimeNewMovieFromFile        40
  292. #define        kABErrBadArgPicHandle                41
  293. #define        kABErrPossibleMemoryLeak            42
  294. #define        kABErrBadArgTopicSlideResource        43
  295. #define        kABErrErrorOpeningSlideFile            44
  296. #define        kABErrInvalidSlideElementCount        45
  297.  
  298. //    dialog resources
  299. //
  300. //    kABmodalDialog is the resource ID# for the about box dialog
  301.  
  302. #define        kABmodalDialog                        5001
  303. #define        kABmoveableModalDialog                5002
  304. #define        kABmodelessDialog                    5003
  305.  
  306. //    kABerror is the resource ID# for the about box alert
  307. //    (error) dialog, used primarily by the ABoxError() function
  308. //    for reporting runtime errors or possible memory leaks
  309. //    to the user/programmer.
  310. #define        kABerror                            5003
  311.  
  312. //    dialog items...
  313. //
  314. //    the following items are the dialog items contained
  315. //    within the kABmodalDialog dialog box.
  316. #define        kAboutBoxOK                            1
  317. #define        kAboutBoxAppAndVersion                2
  318. #define        kAboutBoxTopic                        3
  319. #define        kAboutBoxSlideField                    4
  320. #define        kAboutBoxPrevButton                    5
  321. #define        kAboutBoxNextButton                    6
  322. #define        kAboutBoxPlayButton                    7
  323. //    these next items are pseudo-items, used in mapping
  324. //    up/down arrows to DITL objects
  325. #define        kAboutBoxPreviousTopic                8
  326. #define        kAboutBoxNextTopic                    9
  327.  
  328. #define        kActivateControl            0
  329. #define        kDeactivateControl            0
  330.  
  331. //    general bad things...
  332. //
  333. //    these defines are used to provide a more readable context
  334. //    for error checking in the code. This list will constantly
  335. //    vary as modifications are made to the about box.
  336. #define        kABemptyStringLength            (0)
  337. #define        kABbadDialogItem                (0)
  338. #define        kABbadCautionAlertItem            ((short)-1)
  339.  
  340. //    general good things...
  341. //
  342. //    these defines are helpful constants used in various places of
  343. //    the about box code.
  344. #define        kABallocateDialogRecordStorage    ((Ptr)0)
  345. #define        kABdialogInFront                ((WindowPtr)-1)
  346. #define        kABfileNameLength                ((short)32)
  347. #define        kABlongNameLength                ((short)80)
  348. #define        kABstringSeparator                ("\p/")
  349. #define        kABcaseSensitive                (true)
  350. #define        kABcaseInsensitive                (false)
  351. #define        kABdiacriticalSensitive            (true)
  352. #define        kABdiacriticalInsensitive        (false)
  353.  
  354. //    file type information for PBx calls; these defines
  355. //    are usually always used in conjunction with a PBGetCatInfo()
  356. //    call or some other PBxxx file manager function call.
  357. #define        kABpbIsDirectory                0x0010
  358. #define        kABpbQuery1Item                    ((short)0)
  359. #define        kABpbQueryDirectory                ((short)-1)
  360.  
  361.  
  362. /*================ Enums =================*/
  363.  
  364. //     key equates for keyboard navigation of the about box
  365. //
  366. //    the enter, return, and escape keys function as normal in a modal dialog
  367. //    the tab key really isn't used by the about box
  368. //    the backspace really isn't used by the about box
  369. //    the delete really isn't used by the about box
  370. //    the left arrow will move to the preceeding slide
  371. //    the right arrow will move to the next slide
  372. //    the up arrow will move to the preceeding topic
  373. //    the down arrow will move to the next topic
  374. enum  {
  375.         kEnterKey = 0x03, 
  376.         kBackSpace = 0x08, 
  377.         kTabKey = 0x09, 
  378.         kReturnKey = 0x0D, 
  379.         kEscKey = 0x1B, 
  380.         kLeftArrow = 0x1C, 
  381.         kRightArrow = 0x1d, 
  382.         kUpArrow = 0x1e,
  383.         kDownArrow = 0x1f,
  384.         kSpace = 0x20,
  385.         kDeleteKey = 0x7F
  386. };
  387.  
  388.  
  389.  
  390. /*=============== Structs ================*/
  391. /*=============== Typedefs ===============*/
  392. /*========== Function Prototypes =========*/
  393.  
  394.  
  395.  
  396. #endif    // _ABoxDefs_
  397.  
  398. //    end of file
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.